Styling & Customization

Overview

ggguides provides styling functions to customize legend appearance without diving into ggplot2’s theme element hierarchy. The main functions are:

legend_style() - Comprehensive styling (fonts, backgrounds, borders)
legend_keys() - Override key appearance (size, alpha, shape)
legend_order() - Reorder legend entries
legend_wrap() - Multi-column/row layouts
legend_reverse() - Reverse entry order
colorbar_style() - Customize continuous color bar legends

Font Styling with legend_style()

Font Family

Change the font family for legend text:

p + legend_style(family = "serif") + ggtitle("serif")
p + legend_style(family = "mono") + ggtitle("mono")

Title Emphasis

Make the title stand out with separate size and face settings:

p + legend_style(
  size = 12,
  title_size = 14,
  title_face = "bold"
)

Background and Border

Add visual containers around the legend:

p + legend_style(
  background = "grey95"
)

p + legend_style(
  background = "grey95",
  background_color = "grey70"
)

Key Size

Adjust the size of legend keys (color swatches):

p + legend_style(
  key_width = 1.5,
  key_height = 1.5
)

Margin

Control spacing around the legend:

p + legend_style(
  background = "grey95",
  margin = 0.5
)

Full Styling Example

Combine all styling options:

p + legend_style(
  size = 11,
  title_size = 13,
  title_face = "bold",
  family = "sans",
  key_width = 1.2,
  background = "grey95",
  background_color = "grey70",
  margin = 0.3
)

Wrapping Legend Entries

For legends with many entries, legend_wrap() creates multi-column or multi-row layouts.

By Columns

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(ncol = 2)

By Rows

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(nrow = 2)

With Bottom Position

Wrapping works well with horizontal legends:

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(nrow = 2) +
  legend_bottom()

Customizing Legend Keys

When plot aesthetics like small point sizes or low alpha values make legend keys hard to read, legend_keys() overrides the key appearance without affecting the plot.

Enlarging Small Points

p_small <- ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point(size = 1) +
  labs(color = "Cylinders")

p_small + ggtitle("Small points in legend")
p_small + legend_keys(size = 4) + ggtitle("Enlarged legend keys")

Removing Transparency

p_alpha <- ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point(alpha = 0.3, size = 3) +
  labs(color = "Cylinders")

p_alpha + ggtitle("Transparent legend keys")
p_alpha + legend_keys(alpha = 1) + ggtitle("Opaque legend keys")

Combining Overrides

ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point(alpha = 0.3, size = 1) +
  legend_keys(size = 4, alpha = 1)

Targeting Specific Aesthetics

By default, legend_keys() applies to both colour and fill legends. Target specific aesthetics with the aesthetic parameter:

ggplot(mtcars, aes(factor(cyl), mpg, fill = factor(cyl))) +
  geom_boxplot(alpha = 0.5) +
  legend_keys(alpha = 1, aesthetic = "fill")

Reordering Legend Entries

legend_order() changes the order of legend entries without modifying factor levels in your data.

Explicit Order

Specify the exact order you want:

p + legend_order(c("8", "6", "4"))

Using Functions

Apply functions like rev or sort to the current order:

p + legend_order(rev) + ggtitle("Reversed")
p + legend_order(sort) + ggtitle("Sorted")

Other Aesthetics

Reorder legends for fill, shape, or other aesthetics:

ggplot(mtcars, aes(factor(cyl), fill = factor(cyl))) +
  geom_bar() +
  legend_order(c("8", "4", "6"), aesthetic = "fill")

Reversing Legend Order

For simple reversal, legend_reverse() is a convenient shorthand:

p + legend_reverse()

Combining Style Functions

All ggguides functions compose with +:

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_left() +
  legend_style(
    size = 11,
    title_face = "bold",
    background = "grey95"
  )

ggplot(mpg, aes(displ, hwy, color = class)) +
  geom_point() +
  legend_wrap(ncol = 2) +
  legend_bottom() +
  legend_style(size = 10, title_face = "bold")

Styling Continuous Color Bars

For continuous scales, colorbar_style() customizes the color bar appearance.

Basic Usage

p_cont <- ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
  geom_tile()

p_cont

Size Adjustments

Create taller, thinner bars:

p_cont + colorbar_style(width = 0.5, height = 10)

Horizontal Orientation

p_cont + colorbar_style(width = 10, height = 0.5, direction = "horizontal") +
  legend_bottom()

### Adding a Frame

p_cont + colorbar_style(frame = TRUE) + ggtitle("Black frame")
p_cont + colorbar_style(frame = "grey50") + ggtitle("Grey frame")

Removing Ticks

p_cont + colorbar_style(ticks = FALSE, frame = "grey50")

Combined Customization

p_cont + colorbar_style(
  width = 0.5,
  height = 8,
  frame = "grey30",
  ticks_length = 0.3
)

Summary

Function	Purpose	Key Parameters
`legend_style()`	Comprehensive styling	`size`, `title_size`, `title_face`, `family`, `background`, `background_color`, `margin`
`legend_keys()`	Override key appearance	`size`, `alpha`, `shape`, `linewidth`, `aesthetic`
`legend_order()`	Reorder entries	`order` (vector or function), `aesthetic`
`legend_wrap()`	Multi-column layout	`ncol`, `nrow`
`legend_reverse()`	Reverse entry order	None
`colorbar_style()`	Continuous color bar	`width`, `height`, `frame`, `ticks`, `direction`

Learn more:

Legend Positioning for placement control
Patchwork Integration for multi-panel workflows

Gilles Colling

2025-12-15